Lookup Columns

Description

Display columns in a List where the data in the column is 'looked' up in another List, or by calling a Javascript function.

Discussion

The Lookup Columns property allows you to define 'lookups'. A lookup retrieves data by calling a JavaScript function or searching a List control for related data. For example, a List might contain a column called 'ProductId'. Instead of displaying the 'ProductId' value, you might want to instead display the 'ProductName'.

The image below shows a List based on the Order Details table in the sample Northwind database. Notice that the List shows the ProductId, but not the ProductName.

It would be nice to show the Product Description in the List, as shown in the image below:

Obviously this could be done by specifying a SQL join for the List data source where the Order Detail table was joined with the Products table. However, this would mean that much more data would have to be sent over the network as every row of data in the List would include the Product Description field.

A much better approach would be to 'look up' the data on the client-side as the List was being rendered. You might create a second List based on the Products table that has the ProductId and ProductDescription fields in it.

To define a Lookup, click the smart field for the 'Lookup columns' property on the 'List Properties' pane in the List Builder.

This will open the Lookup Columns genie. You can define as many lookups as you want.

Each lookup must have a unique name. The lookup type is either 'List' or 'Function'.

A 'List' lookup will lookup the value in another List. You can Link the list to the Lookup List on one or more fields.

The List that is used as the data source must appear in the UX builder before the List that references it. For example, if the OrderDetails List lookups up values in the Products List, the Products List must appear before the OrderDetails List in the UX builder.

A 'Function' lookup will call a Javascript function that you define and return either a single value, or an object (with multiple values). Data from the current row in the List is passed into the Javascript function. You specify what data from the current row is passed into the Javascript function by setting the 'Lookup field(s)' property in the Lookup Columns builder.

If you specify more than one lookup field (for example, 'Firstname' and 'Lastname'), the lookup fields are passed into the Javascript function in an array. If there is only one lookup field, the value is passed into the Javascript function as a string. Here is an example of a very simple Javascript function that takes an array of input values:

function myLookupFunction(idValues) {
    if(idValues[0] == 'John' && idValues[1] == 'Smith') return 'value1';
    if(idValues[0] == 'John' && idValues[1] == 'Jones') return 'value2';
    return 'Value not found'
}

Once you have defined the Lookup, the fields from the Lookup are available in the 'Available Fields' list in the List Builder.

Notice in the image above, the 'Lookup Name' was set to 'products'.

Notice in the image below the available fields include:

products.ProductId
products.ProductName

The 'products' prefix is derived from the 'Lookup Name'. The list of available fields includes all of the fields in the Lookup List.

Videos

List Control - Lookup Columns

The List control allows you to define 'lookup columns' where the data in the column is 'looked up' either by calling a Javascript function (that you define), or by looking up the value in some other List.

A typical use case for this is a List that shows Order Details. Each row in the list has a 'productId' field. You would like to display the product name for each product id.

In this video we show how to define Lookup Columns in a List.

(You will need to change the connection string for both lists to point to the sample Northwind database in the downloadable component.)

Watch Video

Download Component